/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 */

package org.apache.skywalking.apm.plugin.tomcat78x.define;

import net.bytebuddy.description.method.MethodDescription;
import net.bytebuddy.matcher.ElementMatcher;
import org.apache.skywalking.apm.agent.core.plugin.interceptor.ConstructorInterceptPoint;
import org.apache.skywalking.apm.agent.core.plugin.interceptor.InstanceMethodsInterceptPoint;
import org.apache.skywalking.apm.agent.core.plugin.interceptor.enhance.ClassInstanceMethodsEnhancePluginDefine;
import org.apache.skywalking.apm.agent.core.plugin.match.ClassMatch;

import static net.bytebuddy.matcher.ElementMatchers.any;
import static net.bytebuddy.matcher.ElementMatchers.named;
import static org.apache.skywalking.apm.agent.core.plugin.match.NameMatch.byName;

/**
 * 查看《说明.md》中对Tomcat架构的说明。
 *
 * Tomcat 一般作为服务入口接收 HTTP 或 HTTPS 请求，tomcat-7.x-8.x-plugin 插件要做的事情也比较明确：
 * 1、在请求进入 Web 项目之前进行拦截。
 * 2、检测当前请求是否处于一个 Trace 之中，也就是检测当前请求是否携带了 ContextCarrier。
 *    如果携带了 ContextCarrier，则在创建 TracingContext 时恢复上下文信息，保持实现 Trace 跨进程传递；
 *    如果没携带 ContextCarrier，则会开启一个全新的 TracingContext。
 * 3、创建（或 restart） EntrySpan。
 * 4、记录一些额外的信息。例如，请求相关的 Tags 信息（请求的 URL、Method 信息等），记录当前组件的类型（即 Tomcat）等。
 *
 * 通过对 Tomcat 结构的分析，以及对 tomcat-7.x-8.x-plugin 插件的功能定位分析，相信你已经发现，
 * tomcat-7.x-8.x-plugin 插件在 StandardHostValve 处拦截请求是合适的。Valve 接口中定义的
 * invoke(Request request, Response response) 方法是每个 Valve 的核心逻辑，例如，根据请求
 * 信息进行过滤、修改请求的特殊字段、打印 access log 等，正如前文介绍的，那些特殊功能的 Valve 实
 * 现是可插拔的，而标准 Valve 实现不可删除，这里 StandardHostValve 实现的 invoke() 方法只负责
 * 选择合适的 Context 继续处理请求。
 *
 * 因此，tomcat-7.x-8.x-plugin 插件拦截 StandardHostValve 的 invoke() 方法即可满足之前的需求。
 *
 * ApplicationDispatcherInstrumentation 类负责拦截 Tomcat 中 ApplicationDispatcher 的全部
 * 构造方法以及其 forward()方法，具体的增强逻辑位于 ForwardInterceptor 中。（查看《说明.md》中的重定向部分）
 */
public class ApplicationDispatcherInstrumentation extends ClassInstanceMethodsEnhancePluginDefine {

    private static final String ENHANCE_CLASS = "org.apache.catalina.core.ApplicationDispatcher";
    private static final String ENHANCE_METHOD = "forward";
    public static final String INTERCEPTOR_CLASS = "org.apache.skywalking.apm.plugin.tomcat78x.ForwardInterceptor";

    @Override
    protected ConstructorInterceptPoint[] getConstructorsInterceptPoints() {
        return new ConstructorInterceptPoint[]{
            new ConstructorInterceptPoint() {
                @Override public ElementMatcher<MethodDescription> getConstructorMatcher() {
                    return any();
                }

                @Override public String getConstructorInterceptor() {
                    return INTERCEPTOR_CLASS;
                }
            }
        };
    }

    @Override protected InstanceMethodsInterceptPoint[] getInstanceMethodsInterceptPoints() {
        return new InstanceMethodsInterceptPoint[] {
            new InstanceMethodsInterceptPoint() {
                @Override public ElementMatcher<MethodDescription> getMethodsMatcher() {
                    return named(ENHANCE_METHOD);
                }

                @Override public String getMethodsInterceptor() {
                    return INTERCEPTOR_CLASS;
                }

                @Override public boolean isOverrideArgs() {
                    return false;
                }
            }
        };
    }

    @Override protected ClassMatch enhanceClass() {
        return byName(ENHANCE_CLASS);
    }
}
